ProjectDrag is free drag-and-drop source control software, based on SourceServer from Apple. SourceServer is an AppleEvent-based subset of the MPW Shell which implements the Projector source control commands. See my column in develop issue 23 (pp. 72-6) for information on SourceServer and ProjectDrag basics. This document gives more details of ProjectDrag.
An overview of the basic mechanics of source control may be helpful. A set of databases on a file server mediates access to source files through a checkin/checkout protocol. When one engineer has a file checked out, no other engineer can check it out until the first engineer checks it back in. Checking a file out puts a writeable copy onto a local hard disk or unlocks a copy that is already there. Checking the file in locks the local file and copies its contents into a database on the server. Periodically, each engineer on the project updates all source files – except those that are checked out locally – through an update command.
ProjectDrag provides “applets” (small scriptable drop-on applications) which automate the most common source control operations. Instead of launching the MPW Shell and using its interesting and unique source control user interface, you can simply drop files and folders onto the appropriate applet from the Finder. This version of ProjectDrag has these applets:
• CheckIn: Drop a file onto this icon if it is currently checked out or modify-read-only. It will be checked in if possible. You can also drop a new file onto CheckIn, so long as the file is in a folder where there are other files from the same project, or at least in a folder which has the name of a known project. The new file will be added to the project. Finally, you can drop a folder onto checkin to check in all checked-out or modify-read-only files in that folder.
• CheckOut: Drop a file onto this icon to check it out for modification. It must be a file in a known project. It must not already be checked out to someone else. Your copy must not be already checked out or modify-read-only.
• ModifyReadOnly: Drop a file onto this icon to circumvent checkin/checkout protocols and modify the file directly. The file must not already be checked out or modify-read-only. However, someone else might have it checked out, and you will not prevent others from checking the file out by keeping it modify-read-only. Use this option with caution – it violates the spirit of source control. However, it is sometimes necessary. (For instance, you can't connect to the file server if you are programming on a laptop in a sleazy bar and the cocktail waitress stole your cellular modem.)
• Update: Drop a file or folder onto this icon to bring it up to date with respect to its database. If you drop a folder on Update, only files which are not modifiable will be brought up to date. Folder updating is recursive. If you drop a modifiable file on Update, that means you want to cancel the checkout or modify-read-only changes you have made to that file. Don't worry – you'll be asked for confirmation before your changes are trashed! Dropping a non-modifiable file on Update brings it up to date with the latest revision on the server.
• Obsolete: Drop a file on this icon to obsolete it. You will be asked for confirmation.
• External CheckIn: When you get a file from some external source and need to check it in to your project (replacing a previous version of the same file), drop the file onto this utility. You will be asked which file you want to replace. That file will be checked out, replaced by the new file, and checked in. This is also very useful for CodeWarrior and THINK project files.
• Cancel: You can drop a file on this icon to cancel its checkout or modify-read-only status. In some problematic cases there may be a file that is checked out for modification according to Projector, but you don't have a checked-out copy handy; in such a case, you will be told that the file doesn't seem to be checked out, but you can try to cancel the checkout anyway. If you drop a folder on Cancel, the same operation is applied to all files in the folder, except that files which don't appear to be checked out or MRO will be ignored.
• ProjectDrag Setup: Drop a database file or folder onto ProjectDrag Setup to record its location in your Preferences folder. You don't need to do this before attempting to work with that project; if you ask for an operation on an unknown project, you will be given a chance to select its ProjectorDB. An alias file will be created in the ProjectDrag Preferences folder in your Preferences folder. You can have any number of projects recorded, and you can throw away aliases that you're not using any more.
Note: Things are simplest if your project name is the same as the name of the folder where you keep your files. However, some people prefer to have a different name for their checkout folder. ProjectDrag supports this automatically using a file which it maintains called “Folder Names” in the ProjectDrag Preferences folder. Only the top level of a project can have its checkout folder renamed, though. Sub-projects must have the same names as their checkout folders.
In my column, I referred to the benefits that will be confered by the Copland Finder in terms of providing the applets in an easy-to-use form. Until Copland ships, though, you can use one of several cool application manager packages to do the same thing. I use Malph, by Nitin Ganatra, which I've included in this release.
The ProjectDrag applets handle change comments. A text file can have a comment at the start which keeps track of what was changed in each revision. This is useful for keeping track of your colleagues' changes and for isolating bugs. Right now, ProjectDrag's change comment handling is ad hoc and tied to a particular comment format and set of source file types. I couldn't find a suitable software package that would do generic template-based string munging to support user-defined comment formats, but I hope to make this area of the code more flexible in future versions. If you can live with the format I'm imposing, which was imposed on me by the project on which I am currently working, great. If not, you can descend into Comments.c and associated resources.
To build ProjectDrag yourself, there's one thing you need to know. If you change it and give it to anyone else, you must change the informational windows to reflect your name and a brief description of your changes. The software is free, but my reputation could suffer materially if you make changes and then redistribute software which bears my name alone. I'm doing you a favor by not charging for these utilities, and I'm happy to be helping you; please don't make me regret it!
To build the software, use the MPW Shell command “BuildProgram”. First, though, you need to copy a folder into the source folder. It are not already in place on the CD because it's archived at other places on the same disc, and even a CD can only stand so much waste. The folders is “MoreFiles 1.3”. Simply drag it in at the same level as the folder called “ProjectDrag Sources”. Then use the MPW “Directory” command to go to the source folder into which you dragged these folders, and give the command “BuildProgram ProjectDrag”. This will analyze the makefile named “ProjectDrag.make” and build the applets and their debugging information (“.SYM”) files into the “Targets” folder.
To debug the files, use the VoodooMonkey debugger, which can also be found at various places on Apple developer discs. This is a very friendly 68K-based symbolic debugger, which can debug 68K code either native or emulated.*
(*Yes, that's right: currently ProjectDrag applets are compiled for the 68K. The time spent in the applets, as opposed to SourceServer and the OS, is so small that there would be no perceptible performance improvement from PowerPC native code. I decided to use the time it would take to build a fat version to add features and remove bugs instead; so sue me. However, a future version of the code will have fat applets to make PowerPC purists happy.)
I intend to keep improving this software. Fan letters will be a great motivating factor, especially ones forwarded to me via DEVELOP@APPLELINK.APPLE.COM. (Sending me tremendous amounts of money might be an even better incentive.) Some of the areas I want to explore are, in rough order of likelihood:
• Automatic copyright messages.
• Flexible change comment handling.
• Adding folder selection menu items as appropriate.
• Grouping all user interface queries at the start of the operation.
• Fat applets for PowerPC users.
• Friendly wrappers for more parts of Projector, such as OrphanFiles, RenameProjectorFile, ProjectInfo, and NewProject.
• Mapping error numbers to text descriptions.
• Accelerating Projector operations over ARA.
• Branch and named revision handling.
• Different preferences per project for multi-project engineers.
• Maintenance of a “shadow folder” with current sources on a file server.
• Automatic late-night updating (or mid-morning, depending on your sleep habits).
• Cross-platform source control for Windows.
• Better scriptability, with more events and support for flags like kNeverInteract.
If you do these things yourself, or make any other cool improvements, let me know! I'll see if your changes and your name can be worked into a future master release. My Internet address is tim@toad.com. Use it wisely (someone has to).
Finally, I would like to once again give thanks to all the people whose software I have stolen drawn upon to make this program. However, I am solely responsible for any problems. Special thanks to:
• Leonard Rosenthol, Stephan Somogyi, and Marshall Clow for DropShell.
• Jim Luther for MoreFiles.
• Jens Alfke for SignatureToApp.
• Steve Falkenburg for the Modal Dialog TextEdit UserItem snippet.
• Mike Lockwood for VoodooMonkey.
• Jon Pugh for cheerfully taking a completely inappropriate weekend phone call pleading for a URL for DropShell.
• Beta testers Rick Mann, Deeje Cooley, and Arno Gourdol.
• Anyone I borrowed from but forgot to credit.
• The nice folks at develop, for letting me overcommit myself.
